home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1998 / MacHack 1998.toast / Sessions / Apple Instrumentation SDK / Instrumentation SDK Quick Start next >
Encoding:
Text File  |  1997-07-20  |  7.6 KB  |  121 lines  |  [TEXT/ttxt]
  1. Instrumentation SDK  Quick Start
  2.  
  3. Document version 1.0b3 for Instrumentation SDK  version 1.0.5
  4.  
  5. The Instrumentation SDK  is an incredibly powerful tool but, when you first start, it can seem overwhelmingly complicated.  However, it is easy to get good results with a minimum of effor—you just have to know where to start.  This document provides a simple overview of the SDK and shows how to quickly get up and running with instrumentation.
  6.  
  7. Why Use the Instrumentation SDK  ?
  8.  
  9. The Instrumentation SDK  is a package that lets you add extra code to your program to gather information about how it executes.  With the SDK  you can learn more about how your code executes, including how many times routines are called, what other routines they call, and how much time they take to execute.
  10.  
  11. The Instrumentation SDK  is similar to the profiling option offered by many compilers; however, it is more powerful and flexible, albeit a bit harder to set up.
  12.  
  13. Installation
  14.  
  15. Note: The rest of this document assumes that {SDK} represents the path to the Instrumentation SDK  and {Boot} represents the root directory of the boot volume on the target computer.
  16.  
  17. To install the SDK on your target machine (i.e., the machine on which you debug your programs—it must be a PowerPC computer), complete the following steps:
  18.  
  19. 1. Drag the contents of the "{SDK}Contents -> Extensions:" to the target machine’s Extensions folder.
  20.  
  21. 2. Drag the contents of the "{SDK}Contents -> root of bootVol" to the {Boot}.
  22.  
  23. You do not need to restart.
  24.  
  25. Testing the Installation
  26.  
  27. Before you start instrumenting your code, you should test your setup on the target machine with the following steps:
  28.  
  29. 1. Double click "{SDK}Test Target:Viewer files:InstTest view." The “Instrumentation Viewer” application opens the file.  "InstTest view" is a view document that has been set up to display the traces that you are about to generate.
  30.  
  31. 2. Run the "{SDK}Test Target:InstTest" application.  This program has been pre-instrumented to generate trace information, which is captured by InstrumentationLib and held in RAM.
  32.  
  33. 3. Run the "{Boot}Instrumentation ƒ:OneShot Collector" application to take the trace information generated by the “InstTest” application and write it to a file "{Boot}Instrumentation ƒ:Instrumentation Data."
  34.  
  35. 4. Drag the "{Boot}Instrumentation ƒ:Instrumentation Data," and drop it on the "Intrumentation Viewer" application. (Double clicking the document may not work.)  This creates a data window that displays all the trace classes.  Use the disclosure triangles to view the individual entries.  Also, the "InstTest view" window will now display the trace data in a graphic form.  If not, make sure you have Browse Mode selected in the Control menu.
  36.  
  37. If you have problems, make sure:
  38.  
  39. a) the Instrumentation package is installed correctly (see previous section).
  40.  
  41. b) you keep the “Instrumentation Viewer” application running while you capture traces. (While this isn’t strictly required, it prevents the InstrumentationLib from unloading from memory and taking your trace data with it!)
  42.  
  43. c) you do not run any of the other applications in the "Instrumentation ƒ".  These spoolers are used for gathering trace information that won’t fit in RAM, and you don’t need to worry about that for the moment.
  44.  
  45. d) you check the "Instrumentation Data." If it is very small (exactly 256 bytes), it is  because you have not captured any trace information.  Check points ( b) and ( c) above.
  46.  
  47. Instrumenting Your Code
  48.  
  49. Once you have made sure that your target machine is working, you can instrument your own PowerPC code with the following steps:
  50.  
  51. 1. Add the ":Interfaces & Libraries:SharedLibraries:InstrumentationLib" library to your project.
  52.  
  53. 2. Include the "InstrumentationMacros.h" header file in your source.
  54.  
  55. 3. In each function you want to instrument, add the instrumentation constructs as shown below:
  56.  
  57. static void RoutineBeforeInstrumenting(void)
  58.   // If this is what your routine looks like...
  59. {
  60.   MyType myVariable;
  61.  
  62.   myVariable = MyStatement();
  63.   MyOtherStatement(myVariable);
  64. }
  65.  
  66. static void RoutineAfterInstrumenting(void)
  67.   // ... you can instrument it as such.
  68. {
  69.   TRACE_SETUP;
  70.   MyType myVariable;
  71.  
  72.   LOG_ENTRY( "MyApplicationName:RoutineAfterInstrumenting" );
  73.   myVariable = MyStatement();
  74.   MyOtherStatement(myVariable);
  75.   LOG_EXIT;
  76. }
  77.  
  78. 4. Quit all applications that use InstrumentationLib that are running on the target machine.  This will clear out any residual trace data from RAM.  Then relaunch the "Instrumentation Viewer" application.  This will open a new, untitled view window.
  79.  
  80. 5. Run your code on the target machine.  This trace data is captured by InstrumentationLib and held in RAM.
  81.  
  82. 6. Run the "OneShot Collector" application (in the "Instrumentation ƒ" folder) to write your trace data into the "Instrumentation Data" file in the "Instrumentation ƒ" folder.  The previous contents of the file are overwritten.
  83.  
  84. 7. Open the "Instrumentation Data" with "Instrumentation Viewer."  The new window should contain an item labelled MyApplicationName (or whatever name you used in the LOG_ENTRY call).  If you hit the disclosure triangle, you should see an item for each different function you instrumented.
  85.  
  86. 8. Now choose Show Viewer Palette from the Window menu.  Drag a Trace Time Line Viewer item from the palette into the view document window (this should still be "untitled," not the "Instrumentation Data" window) .  This should create a new Trace Time Line Viewer item in your view document.
  87.  
  88. 9. Drag one of the trace items (e.g., "RoutineAfterInstrumenting") from the "Instrumentation Data" window into the Trace Time Line Viewer.
  89.  
  90. 10. Choose Switch to Browse Mode from the Control menu and wonder at the magic trace view of your code.  From this view you can see how long each of your instrumented functions took to run, and what other instrumented functions it called.
  91.  
  92. The Instrumentation SDK  can also be used for 68K code running on PowerPC machines; see "Inst. Programmer's Guide.pdf" for details.
  93.  
  94. Instrumenting Your External Calls
  95.  
  96. Of course it’s likely that your program will spend a lot of time not running its own code but running in the operating system. You can automatically instrument your calls to the operating system using the "MrPlus" MPW tool.  (MrPlus is available on the ETO CD.) To use MrPlus to instrument all your calls to external libraries, use the following MPW command line:
  97.  
  98.   MrPlus MyProgramFile -instrument imports -member MyFragmentName
  99.  
  100. where MyProgramFile is the name of the file that contains your program and MyFragmentName is the name of the CFM fragment for your program.  This creates a file called "MyProgramFile.prof", which has been modified to make instrumentation calls.  Before you execute this modified binary, make sure you install "{SDK}Test Target:ProfileLib" in your Extensions folder.
  101.  
  102. You can also supply options to "MrPlus" to only instrument specific calls you make, or to automatically instrument some or all of your exports.  (This is particularly useful if you are a device driver.)  See the last page "{SDK}Documentation:Inst. System User's Guide.pdf" for more details.
  103.  
  104. But Wait, There’s More
  105.  
  106. This Quick Start only scratches the surface of what you can do with the Instrumentation SDK.  For more information, check out the other documents in this SDK:
  107.  
  108. • "{SDK}Documentation:Inst. System User's Guide.pdf" describes the various components of the instrumentation system and how they interact.
  109.  
  110. • "{SDK}Documentation:Inst. Programmer's Guide.pdf" describes the "Instrumentation.h" API in detail.
  111.  
  112. • "{SDK}Documentation:Inst. Viewer User's Guide.pdf" is a user and reference manual for the "Intrumentation Viewer" application.
  113.  
  114. Share and Enjoy
  115.  
  116. Quinn "The Eskimo!"
  117. Apple Developer Technical Support
  118. Networking, Communications, Hardware
  119.  
  120. 10 Apr 1997
  121.